<!DOCTYPE HTML>
<html>
<head>
<title>ComObjActive() | AutoHotkey</title>
<meta name="description" content="The ComObjActive function retrieves a running object that has been registered with OLE." />
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<meta http-equiv="X-UA-Compatible" content="IE=edge">
<link href="../static/theme.css" rel="stylesheet" type="text/css" />
<script src="../static/content.js" type="text/javascript"></script>
<script type="text/javascript">$(function(){0<=window.navigator.userAgent.toLowerCase().indexOf("ucbrowser")&&CaoNiMaDeUc()})</script>
</head>
<body>

<h1>ComObjActive() <span class="ver">[AHK_L 53+]</span></h1>

<p>检索已使用 OLE(对象连接与嵌入) 注册的运行对象.</p>
<pre class="Syntax">ComObject := <span class="func">ComObjActive</span>(CLSID)</pre>

<p id="param">创建一个表示要作为参数或返回值传递的类型化值的对象.</p>
<pre class="Syntax">ParamObj := <span class="func">ComObject</span>(VarType, Value <span class="optional">, Flags</span>)</pre>
<hr>
<p class="warning"><strong>过时的:</strong> 不推荐使用以下方法, 后续版本中可能被替换或不再支持.</p>
<p id="missing">在调用 COM(组件对象模型) 对象的方法时创建一个可用于替代可选参数默认值的对象. <span class="ver">[v1.1.12+]</span>: 这种函数已废弃使用. 作为代替, 使用两个连续的逗号, 如 <code>Obj.Method(1,,3)</code></p>
<pre class="Syntax">ParamObj := <span class="func">ComObjMissing</span>()</pre>

<p id="enwrap">装包或拆包位于可用对象的原始 <a href="http://msdn.microsoft.com/en-us/library/dd318520.aspx">IDispatch</a> 指针, 并自动调用 AddRef(增加引用).</p>
<pre class="Syntax">
ComObject := <span class="func">ComObjEnwrap</span>(DispPtr)
DispPtr := <span class="func">ComObjUnwrap</span>(ComObject)
</pre>
<p>要写更多面向未来的代码, 请改用以下代码:</p>
<pre>ComObject := ComObject(9, DispPtr, 1), ObjAddRef(DispPtr)
DispPtr := <a href="ComObjValue.htm">ComObjValue</a>(ComObject), ObjAddRef(DispPtr)</pre>
<hr>

<h2 id="Parameters">参数</h2>
<dl>

  <dt>CLSID</dt>
  <dd><p>要检索的 COM 对象的 CLSID 或可读 Prog ID.</p></dd>

  <dt>ComObject</dt>
  <dd><p>可以使用<a href="../Objects.htm#Usage_Objects">对象语法</a>的 COM 对象.</p></dd>

  <dt>VarType</dt>
  <dd><p>表示值类型的整数. 类型列表见 <a href="ComObjType.htm#vt">ComObjType()</a>.</p></dd>

  <dt>Value</dt>
  <dd><p>要包装的值. 当前仅支持整数值和指针值.</p></dd>

  <dt>Flags</dt>
  <dd><p>影响此函数和包装器对象行为的标志, 请参阅后面.</p></dd>

  <dt>DispPtr</dt>
  <dd><p>原始的 IDispatch 指针.</p></dd>

</dl>

<h2 id="Flags">Flags</h2>
<table class="info">
  <tr>
    <th class="center">Flag</th>
    <th>作用</th>
  </tr>
  <tr>
    <td class="center">0</td>
    <td>
      <p>默认行为. <a href="http://msdn.microsoft.com/en-us/library/ms691379.aspx">AddRef(增加引用)</a> 自动调用 IUnknown 和 IDispatch 的指针, 所以调用者应该适当使用 <a href="ObjAddRef.htm">ObjRelease()</a> 释放指针的副本.</p>
      <p>未来版本中可能改变此默认行为, 因此建议当包装接口指针时总是设置 <em>标志</em> 为 <code>1</code>, 需要时再调用 <a href="ObjAddRef.htm">ObjAddRef()</a>.</p>
    </td>
  </tr>
  <tr>
    <td class="center">1</td>
    <td>取得 IUnknown, IDispatch 或 SAFEARRAY(安全数组) 指针的所有权. 不调用 AddRef. 如果包装器对象包含 SAFEARRAY(VT_BYREF 除外), 那么当包装器对象被释放时会自动调用 <a href="https://msdn.microsoft.com/en-us/library/ms221702(v=vs.85).aspx">SafeArrayDestroy</a>.</td>
  </tr>
</table>

<h2 id="ByRef">ByRef <span class="ver">[v1.1.17+]</span></h2>
<p>如果包装器对象的 <a href="ComObjType.htm"><em>变量类型</em></a> 包含 VT_BYREF(0x4000) 标签, 可用空的方括号对 <code>[]</code> 来读写引用的值.</p>
<p>当创建一个引用, <em>值</em> 须为变量的内存地址, 或足够存储指定类型的值的缓存. 例如, 下面的代码可以用来创建一个 VBScript 函数可以写入的变量:</p>
<pre>VarSetCapacity(var, 24, 0)
vref := ComObject(0x400C, &amp;var)  <em>; 0x400C 是 VT_BYREF 与 VT_VARIANT 组合而得.</em>

vref[] := "in value"
sc.Run("Example", vref)  <em>; sc 应像<a href="#ByRefEx">下面例子</a>一样进行初始化.</em>
MsgBox % vref[]</pre>
<p>请注意, 尽管在通过 <code>vref[]</code> 或 COM 方法分配新值时, 任何先前的值都会被释放, 但最终的值不会被自动释放. 释放该值需要知道它是哪种类型. 因为如果是 VT_VARIANT, 它可以通过使用 <a href="DllCall.htm">DllCall</a> 调用 <a href="https://docs.microsoft.com/en-us/windows/win32/api/oleauto/nf-oleauto-variantclear">VariantClear</a>,  或使用一个更简单的方法来释放: 赋值一个整数, 如 <code>vref[] := 0</code>.</p>

<h2 id="Remarks">备注</h2>
<p>当前版本中, 任何以 "ComObj" 开头的函数调用, 如果不匹配目录列表中的其他 COM 函数, 则实际调用 ComObjActive 函数. 如, <code>ComObjEnwrap(DispPtr)</code> 及 <code>ComObjActive(DispPtr)</code> 均等效于 <code>ComObject(DispPtr)</code>(隐式地, <em>变量类型</em> 为 9). 此行为可能于后续版本不再可用, 故建议仅使用本页所展示的 <code>ComObject()</code> 及 <code>ComObjActive()</code>.</p>
<p>如果 ComObjActive 不能检索活动的对象, 则可能会抛出异常, 退出脚本或返回空字符串, 具体取决于当前的 <a href="ComObjError.htm">ComObjError()</a> 设置和<a href="ComObjError.htm#factors">其他因素</a>.</p>
<p>当使用此函数包装或检索 IDispatch 或 IUnknown 接口指针时, 默认的行为会增加 COM 对象的引用计数. 因此, 当不使用时, 须<a href="ObjAddRef.htm">手动释放</a>接口指针. 当用于封装的对象被释放时, 他所包含的引用被自动释放.</p>
<p><b>已知限制:</b> 每次包装 COM 对象时, 都会创建新的包装器对象. 如 <code>if (obj1 == obj2)</code>, <code>array[obj1] := value</code> 这样的比较和赋值运算, 会把两个包装器对象视为独立的, 即使它们包含相同的 COM 对象.</p>

<h2 id="Related">相关</h2>
<p><a href="ComObjCreate.htm">ComObjCreate()</a>, <a href="ComObjGet.htm">ComObjGet()</a>, <a href="ComObjConnect.htm">ComObjConnect()</a>, <a href="ComObjError.htm">ComObjError()</a>, <a href="ComObjFlags.htm">ComObjFlags()</a>, <a href="ObjAddRef.htm">ObjAddRef() / ObjRelease()</a>, <a href="ComObjQuery.htm">ComObjQuery()</a>, <a href="http://msdn.microsoft.com/en-us/library/ms221467.aspx">GetActiveObject (MSDN)</a></p>

<h2 id="Examples">示例</h2>
<p>ComObjUnwrap(COM 对象拆包): 参见 <a href="ComObjConnect.htm#Examples">ComObjConnect()</a>.</p>
<div class="ex" id="ByRefEx">
<p><a class="ex_number" href="#ByRefEx"></a> 传递 VARIANT ByRef 给 COM 函数.</p>
<pre>
<em>; 条件 - ScriptControl 需 32 位版本的 AutoHotkey.</em>
code =
(
Sub Example(Var)
    MsgBox Var
    Var = "out value!"
End Sub
)
sc := <a href="ComObjCreate.htm">ComObjCreate</a>("ScriptControl"), sc.Language := "VBScript", sc.AddCode(code)


<em>; 示例: 传递 VARIANT ByRef 至 COM 函数.</em>
var := ComVar()
var[] := "in value"  <em>; 使用 [] 来赋值.</em>
sc.Run("Example", var.ref)  <em>; 传递 VT_BYREF ComObject (.ref).</em>
MsgBox % var[]  <em>; 使用 [] 来检索值.</em>

<em>; 同样的事情, 但更直接:</em>
VarSetCapacity(variant_buf, 24, 0)  <em>; 使 VARIANT 的缓冲足够大.</em>
var := ComObject(0x400C, &amp;variant_buf)  <em>; 引用 VARIANT.</em>
var[] := "in value"
sc.Run("Example", var) <em> ; 传递 VT_BYREF ComObject 本身, 没有 [] 或 .ref.</em>
MsgBox % var[]
<em>; 如果 VARIANT 包含一个字符串或对象, 必须显式地释放它
; 通过调用 VariantClear 或赋值一个纯数字值来释放:</em>
var[] := 0

<em>; ComVar: 创建可用于按引用(ByRef) 传值的对象.
;   ComVar[] 返回值.
;   ComVar[] := Val 设置值.
;   ComVar.ref 返回用于 COM 函数的按引用传值的对象.</em>
ComVar(Type := 0xC)
{
    static base := { __Get: Func("ComVarGet"), __Set: Func("ComVarSet")
        , __Delete: Func("ComVarDel") } <em>; 有关 base, 请参阅自定义对象.
    ; 基于 base 创建一个新的对象.</em>
    cv := {base: base}

    <em>; 为 VARIANT 分配内存, 以保存我们的值.
    ; 即使 Type != VT_VARIANT 也会使用 VARIANT, 以便 VariantClear 可以被 __delete 使用.</em>
    cv.SetCapacity("buf", 24), ptr := cv.GetAddress("buf")
    NumPut(0, NumPut(0, ptr+0, "int64"), "int64")

    if (Type != 0xC) { <em>; 不是 VT_VARIANT.</em>
        NumPut(Type, ptr+0, "ushort") <em>; 为 __delete 设置变体类型.</em>
        ptr += 8 <em>; 实际值的指针.</em>
    }

    <em>; 创建一个对象, 可以用来传递变量 ByRef.</em>
    cv.ref := ComObject(0x4000|Type, ptr)

    return cv
}

ComVarGet(cv, p*) { <em>; 当脚本访问未知字段时调用.</em>
    if p.MaxIndex() = "" <em>; 没有名称/参数, 如, cv[]</em>
        return cv.ref[]
}

ComVarSet(cv, v, p*) { <em>; 当脚本设置未知字段时调用.</em>
    if p.MaxIndex() = "" <em>; 没有名称/参数, 如, cv[]:=v</em>
        return cv.ref[] := v
}

ComVarDel(cv) { <em>; 当对象被释放时调用.
    ; 根据类型的不同, 如果设置了, 可能需要释放这个值.</em>
    DllCall("oleaut32\VariantClear", "ptr", cv.GetAddress("buf"))
}
</pre>
</div>

</body>
</html>